<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="rustdoc">
    <title>Native Windows GUI guide - Derive controls</title>

    <link rel="stylesheet" type="text/css" href="style/rustbook.css">
    <link rel="stylesheet" type="text/css" href="style/pygments.css">
    <link rel="stylesheet" type="text/css" href="style/nwg.css">

</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
    This old browser is unsupported and will most likely display funky
    things.
</div>
<![endif]-->

<!-- NAV BEGIN -->
<div id="nav">
    <button id="toggle-nav">
        <span class="sr-only">Toggle navigation</span>
        <span class="bar"></span>
        <span class="bar"></span>
        <span class="bar"></span>
    </button>
</div>

    
<div id='toc' class='mobile-hidden'>
<ul class='chapter'>
<li><a href='index.html'><b>1.</b> Introduction</a>
</li>
<li><a href='getting_started.html'><b>2.</b> Getting Started</a>
</li>

<li><a href="basics.html"><b>3.</b> Basics </a>
<ul class="section">
    <li><a href="controls.html"><b>3.1.</b> Controls </a></li>
    <li><a href="events.html"><b>3.2.</b> Events </a></li>
    <li><a href="helper.html"><b>3.3.</b> Helpers </a></li>
    <li><a href="small.html"><b>3.4.</b> Small application layout </a></li>
    <li><a href="limitations.html"><b>3.5.</b> Limitations </a></li>
    <li><a href="distribute.html"><b>3.6.</b> Distributing </a></li>
    <li><a href="features.html"><b>3.7.</b> Features </a></li>
</ul>
</li>

<li><a href="intermediate.html"><b>4.</b> Intermediate </a>
<ul class="section">
    <li><a href="layouts.html"><b>4.1.</b> Layouts </a></li>
    <li><a href="resources.html"><b>4.2.</b> Resources </a></li>
    <li><a href="dialogs.html"><b>4.3.</b> Dialogs </a></li>
    <li><a href="localization.html"><b>4.4.</b> Internationalization </a></li>
</ul>
</li>

<li><a href="advanced.html"><b>5.</b> Advanced </a>
<ul class="section">
    <li><a href="partial.html"><b>5.1.</b> Partials ui </a></li>
    <li><a href="dynamic_control.html"><b>5.2.</b> Dynamic control </a></li>
    <li><a href="dynamic_event.html"><b>5.3.</b> Dynamic events </a></li>
    <li><a href="multithreading.html"><b>5.4.</b> Multithreading </a></li>
</ul>
</li>

<li><a href="derive.html"><b>6.</b> Native-windows-derive </a>
<ul class="section">
    <li><a href="nwd_basics.html"><b>6.1.</b> Basics </a></li>
    <li><a href="nwd_controls.html"><b>6.1.</b> Controls </a></li>
    <li><a href="nwd_resources.html"><b>6.2.</b> Resources </a></li>
    <li><a href="nwd_events.html"><b>6.3.</b> Events </a></li>
    <li><a href="nwd_layouts.html"><b>6.4.</b> Layouts </a></li>
    <li><a href="nwd_partial.html"><b>6.5.</b> Partials </a></li>
</ul>
</li>

<li><a href="low.html"><b>7.</b> Low level stuff </a>
    <ul class="section">
        <li><a href="low_events.html"><b>7.1.</b> Raw event handling </a></li>
        <li><a href="extern_wrapping.html"><b>7.2.</b> Raw control handle </a></li>
    </ul>
</li>

</ul>
</div>
<!-- NAV END -->

<div id='page-wrapper'>
    <div id='page'>

        <h1 class="title">Native Windows Derive: Controls</h1>
        The first thing to define in a derive UI are the controls. Native windows derive maps a list of attributes to the builder api.
        This way, definining the control parameters will only take a single line above the struct member definition.<br><br>

        Also, be sure to check out the <a href="controls.html">controls docs</a>.

        <br/><br/>

        <h3>Attributes</h3>

        As mentioned in the controls docs, almost every components of NWG use the same builder based approach. Builders API are easy
        to understand at the cost of being verbose. In order to keep UI the initialization to a minimum, NWD translates the builder API
        into a list of 
        
        <br><br>
        <code>nwg_control(builder_field: builder_value,*)</code>
        <br><br>

        This has the benefits of keeping boilerplate code to a minimal amount and it also keep the control parameters next to the type definition,
        making things easier to understand for anyone reading the code.<br><br>

        Example:<br>

<div class="highlight"><pre style="width:auto;"><span></span><span class="cp">#[nwg_control(text: </span><span class="s">&quot;Heisenberg&quot;</span><span class="cp">, size: (280, 25), position: (10, 10))]</span><span class="w"></span>
<span class="n">name_edit</span>: <span class="nc">nwg</span>::<span class="n">TextInput</span><span class="p">,</span><span class="w"></span>

<span class="c1">// is the same as </span>

<span class="n">nwg</span>::<span class="n">TextInput</span>::<span class="n">builder</span><span class="p">()</span><span class="w"></span>
<span class="w">    </span><span class="p">.</span><span class="n">text</span><span class="p">(</span><span class="s">&quot;Heisenberg&quot;</span><span class="p">)</span><span class="w"></span>
<span class="w">    </span><span class="p">.</span><span class="n">size</span><span class="p">((</span><span class="mi">280</span><span class="p">,</span><span class="w"> </span><span class="mi">25</span><span class="p">))</span><span class="w"></span>
<span class="w">    </span><span class="p">.</span><span class="n">position</span><span class="p">((</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">10</span><span class="p">))</span><span class="w"></span>
<span class="w">    </span><span class="p">.</span><span class="n">build</span><span class="p">(&mut data.text_edit);</span><span class="w"></span>
</pre></div>

        <h3>Parent detection</h3>

        In most circumstances, the controls in a UI will have the same parent; the window. Because nobody wants to copy and paste "<code>parent: window</code>"
        on each children controls, the derive macro can guess the parent by looking up the fields defined before the control in the UI struct. Derive will choose the first
        control marked with <code>nwg_control</code> that supports children.
        <br><br>

        If no parent is defined in the attributes, and no parent can be guessed the parent value will be left empty. The derive macro will not panic, but the resulting
        code will raise a <code>ControlCreationError("no parent")</code> error.
        <br><br>

        Here is an example that shows how NWD guess the parents:

<div class="highlight"><pre style="width:auto"><span></span><span class="cp">#[derive(NwgUi)]</span><span class="w"></span>
<span class="k">struct</span> <span class="nc">MyUi</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="c1">// No auto parent</span>
<span class="w">    </span><span class="n">label</span>: <span class="nc">nwg</span>::<span class="n">Label</span><span class="p">,</span><span class="w"></span>

<span class="w">    </span><span class="c1">// No auto parent</span>
<span class="w">    </span><span class="n">window</span>: <span class="nc">nwg</span>::<span class="n">Window</span><span class="p">,</span><span class="w"></span>

<span class="w">    </span><span class="c1">// parent: window</span>
<span class="w">    </span><span class="n">label</span>: <span class="nc">nwg</span>::<span class="n">Label</span><span class="p">,</span><span class="w"></span>

<span class="w">    </span><span class="c1">// parent: window</span>
<span class="w">    </span><span class="n">frame</span>: <span class="nc">nwg</span>::<span class="n">Frame</span><span class="p">,</span><span class="w"></span>

<span class="w">    </span><span class="c1">// parent: frame</span>
<span class="w">    </span><span class="n">button</span>: <span class="nc">nwg</span>::<span class="n">Button</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>

        <h3>Compressed flags</h3>

        Defining flags can take alot of space. In order to fix this, NWG supports a "compressed" flags format. Where the flag enum is ignored.
        This only works with the <code>flags</code> parameters because it's possible for NWD to guess the right type. For example, here's the
        compressed flag definition VS the normal flag definition.<br><br>

        It's also worth noting that there is no need to import NWG in the local scope of your module when using native window values (such as flags definition).


<div class="highlight"><pre style="width: auto;"><span ></span><span class="cp">#[derive(NwgUi)]</span><span class="w"></span>
<span class="k">struct</span> <span class="nc">MyUi</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[nwg_control(flags: </span><span class="s">&quot;WINDOW|VISIBLE&quot;</span><span class="cp">)]</span><span class="w"></span>
<span class="w">    </span><span class="n">window1</span>: <span class="nc">nwg</span>::<span class="n">Window</span><span class="p">,</span><span class="w"></span>

<span class="w">    </span><span class="cp">#[nwg_control(flags: WindowFlags::WINDOW | WindowFlags::VISIBLE)]</span><span class="w"></span>
<span class="w">    </span><span class="n">window1</span>: <span class="nc">nwg</span>::<span class="n">Window</span><span class="p">,</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
            
        <h3>Subclassed controls</h3>

        By default, NWD can guess the control builder by looking up the structure member type. When a user type is used, this is no longer possible.
        To fix this, it's possible to pass the <code>ty</code> parameter to the <code>nwg_control</code> attribute. <code>ty</code> won't be evaluated
        as a builder parameter.
        <br><br>

        When not using <code>ty</code> and still using custom values, NWD will try to instance a custom builder object by calling <code>MyType::builder</code>.
        The custom builder must work in the same way built-in builders works.
        <br><br>

        For an example see: <a href="https://github.com/gabdube/native-windows-gui/blob/master/native-windows-gui/examples/subclassing_d.rs">the subclassing example.</a>

<div class="highlight"><pre style="width: auto;"><span></span><span class="k">struct</span> <span class="nc">CustomButton1</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">base</span>: <span class="nc">nwg</span>::<span class="n">Button</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="k">struct</span> <span class="nc">CustomButton2</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">base</span>: <span class="nc">nwg</span>::<span class="n">Button</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="k">struct</span> <span class="nc">CustomButton2Builder</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="k">pub</span><span class="w"> </span><span class="k">fn</span> <span class="nf">build</span><span class="p">(</span><span class="n">btn</span>: <span class="kp">&amp;</span><span class="nc">mut</span><span class="w"> </span><span class="n">CustomButton2</span><span class="p">)</span><span class="w"> </span>-&gt; <span class="nb">Result</span><span class="o">&lt;</span><span class="p">(),</span><span class="w"> </span><span class="n">nwg</span>::<span class="n">NwgError</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="c1">//...</span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="n">subclass_control</span><span class="o">!</span><span class="p">(</span><span class="n">CustomButton1</span><span class="p">,</span><span class="w"> </span><span class="n">Button</span><span class="p">,</span><span class="w"> </span><span class="n">base</span><span class="p">);</span><span class="w"></span>
<span class="n">subclass_control</span><span class="o">!</span><span class="p">(</span><span class="n">CustomButton2</span><span class="p">,</span><span class="w"> </span><span class="n">Button</span><span class="p">,</span><span class="w"> </span><span class="n">base</span><span class="p">);</span><span class="w"></span>

<span class="cp">#[derive(NwgUi)]</span><span class="w"></span>
<span class="k">struct</span> <span class="nc">MyUi</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[nwg_control]</span><span class="w"></span>
<span class="w">    </span><span class="n">window1</span>: <span class="nc">nwg</span>::<span class="n">Window</span><span class="p">,</span><span class="w"></span>

<span class="w">    </span><span class="cp">#[nwg_control(ty=Button)]</span><span class="w"></span>
<span class="w">    </span><span class="n">test_button1</span>: <span class="nc">CustomButton1</span><span class="p">,</span><span class="w"></span>

<span class="w">    </span><span class="cp">#[nwg_control]</span><span class="w"></span>
<span class="w">    </span><span class="n">test_button2</span>: <span class="nc">CustomButton2</span><span class="p">,</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
            
            
        <br/><br/>

    </div>
</div>

<script src="style/rustbook.js"></script>
</body>
</html>
